golden-fleece

What is golden-fleece?

The golden-fleece npm package is a utility for parsing and stringifying JavaScript objects with comments. It allows you to manipulate JavaScript objects while preserving comments, which can be useful for configuration files and other scenarios where comments are important.

What are golden-fleece's main functionalities?

Parsing JavaScript objects with comments

This feature allows you to parse a JavaScript object from a string while preserving comments. The `parse` method takes a string input and returns a JavaScript object.

const goldenFleece = require('golden-fleece');
const input = `{
  // This is a comment
  foo: 42,
  bar: 'baz'
}`;
const parsed = goldenFleece.parse(input);
console.log(parsed);

Stringifying JavaScript objects with comments

This feature allows you to convert a JavaScript object back into a string while adding comments. The `stringify` method takes an object and an optional comments object, and returns a string representation of the object with comments.

const goldenFleece = require('golden-fleece');
const obj = {
  foo: 42,
  bar: 'baz'
};
const output = goldenFleece.stringify(obj, {
  comments: {
    foo: 'This is a comment'
  }
});
console.log(output);

Other packages similar to golden-fleece

comment-json

The comment-json package allows you to parse and stringify JSON with comments. It is similar to golden-fleece but focuses specifically on JSON rather than general JavaScript objects. It provides similar functionality for preserving comments during parsing and stringifying.

json5

The json5 package is a JSON parser and stringifier that supports comments and more relaxed JSON syntax. It is similar to golden-fleece in that it allows comments in JSON, but it also supports other JSON5 features like trailing commas and unquoted property names.

README

golden-fleece

Parse a JSON5 string (like JSON, but less strict).

Why?

For the Svelte REPL, where we want to allow arbitrary data in the bottom right-hand panel, but we also want to update the object without reformatting it as JSON.

Usage

Install it with npm install golden-fleece and import it into your app:

import * as fleece from 'golden-fleece';

fleece.parse(str, [options])

const ast = fleece.parse(`true`);
// { start: 0, end: 4, type: 'Literal', raw: 'true', value: true }

The returned AST is ESTree compliant.

You can optionally pass callbacks that are fired whenever a value or comment is encountered:

const ast = fleece.parse(str, {
	onComment: comment => {
		console.log('got a comment', comment);
	},
	onValue: value => {
		console.log('got a value', value);
	}
});

fleece.evaluate(str)

const { answer } = fleece.evaluate(`{ answer: 42 }`);
answer === 42; // true

fleece.patch(str, value)

This is where it gets fun:

const str = `
	number: 1,
	string: 'yes',
	object: { nested: true },
	array: ['this', 'that', 'the other']
`;

const object = fleece.evaluate(str);
object.number = 42;
object.array[2] = 'EVERYTHING';

fleece.patch(str, object) === `{
	number: 42,
	string: 'yes',
	object: { nested: true },
	array: ['this', 'that', 'EVERYTHING']
}`; // true

Notice that the formatting has been preserved.

fleece.stringify(value, [options])

const object = {
	string: 'hello',
	'quoted-property': 2,
	array: [3, 4]
};

fleece.stringify(object) === `{
	string: "hello",
	"quoted-property": 2,
	array: [
		3,
		4
	]
}`; // true

To indent with spaces instead of tabs, pass spaces: n, where n is the number of spaces at each level of indentation.

fleece.stringify(object, {
	spaces: 2
}) === `{
  string: "hello",
  "quoted-property": 2,
  array: [
    3,
    4
  ]
}`; // true

To prefer single-quotes to double-quotes, pass singleQuotes: true:

fleece.stringify(object, {
	singleQuotes: true
}) === `{
	string: 'hello',
	'quoted-property': 2,
	array: [
		3,
		4
	]
}`; // true

License

LIL

Changelog

1.0.9

• Various fixes/improvements to number patching (#16)